<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Application Configuration Resource File - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level3"><a href="girch.html">Using Annotations to Configure Managed Beans</a></p>
<p class="toc level4"><a href="girch.html#gircr">Using Managed Bean Scopes</a></p>
<p class="toc level5"><a href="girch.html#girep">Eager Application-scoped Beans</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3 tocsp"><a href="">Application Configuration Resource File</a></p>
<p class="toc level4"><a href="#giqck">Ordering of Application Configuration Resource Files</a></p>
</div>
<p class="toc level3 tocsp"><a href="bnawq.html">Configuring Beans</a></p>
<p class="toc level4"><a href="bnawq.html#bnawr">Using the <tt>managed-bean</tt> Element</a></p>
<p class="toc level4"><a href="bnawq.html#bnaws">Initializing Properties Using the <tt>managed-property</tt> Element</a></p>
<p class="toc level5"><a href="bnawq.html#bnawu">Referencing a Java <tt>Enum</tt> Type</a></p>
<p class="toc level5"><a href="bnawq.html#bnawv">Referencing an Initialization Parameter</a></p>
<p class="toc level5"><a href="bnawq.html#bnaww">Initializing Map Properties</a></p>
<p class="toc level5"><a href="bnawq.html#bnawx">Initializing Array and List Properties</a></p>
<p class="toc level5"><a href="bnawq.html#bnawy">Initializing Managed Bean Properties</a></p>
<p class="toc level4 tocsp"><a href="bnawq.html#bnaxa">Initializing Maps and Lists</a></p>
<p class="toc level3 tocsp"><a href="bnaxb.html">Registering Custom Error Messages</a></p>
<p class="toc level4"><a href="bnaxb.html#gkuhg">Using <tt>FacesMessage</tt> to Create a Message</a></p>
<p class="toc level4"><a href="bnaxb.html#bnass">Referencing Error Messages</a></p>
<p class="toc level3 tocsp"><a href="bnaxc.html">Registering Custom Localized Static Text</a></p>
<p class="toc level3"><a href="gireb.html">Using Default Validators</a></p>
<p class="toc level3"><a href="bnaxf.html">Configuring Navigation Rules</a></p>
<p class="toc level4"><a href="bnaxf.html#giqwk">Implicit Navigation Rules</a></p>
<p class="toc level3 tocsp"><a href="bnaxj.html">Basic Requirements of a JavaServer Faces Application</a></p>
<p class="toc level4"><a href="bnaxj.html#bnaxk">Configuring an Application With a Web Deployment Descriptor</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxl">Identifying the Servlet for Lifecycle Processing</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxm">Specifying a Path to an Application Configuration Resource File</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxn">Specifying Where State Is Saved</a></p>
<p class="toc level4 tocsp"><a href="bnaxj.html#giqxl">Configuring Project Stage</a></p>
<p class="toc level4"><a href="bnaxj.html#bnaxt">Including the Classes, Pages, and Other Resources</a></p>
<p class="toc level2 tocsp"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level2"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="girch.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="bnawq.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bnawp"></a><h2>Application Configuration Resource File</h2>
<a name="indexterm-768"></a><a name="indexterm-769"></a><p>JavaServer Faces technology provides a portable configuration format (as an XML document) for
configuring application resources. One or more XML documents, called application configuration resource files,
may use this format to register and configure objects and resources, and to
define navigation rules for applications. An application configuration resource file is usually named <tt>faces-config.xml</tt>.</p>

<p>You need an application configuration resource file in the following cases:</p>


<ul><li><p>To specify configuration elements for your application that are not available through managed bean annotations, such as localized messages and navigation rules</p>

</li>
<li><p>To override managed bean annotations when the application is deployed</p>

</li></ul>
<p>The application configuration resource file must be valid against the XML schema located
at <a href="http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd">http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd</a>.</p>

<p>In addition, each file must include the following information, in the following order:</p>


<ul><li><p>The XML version number, usually with an <tt>encoding</tt> attribute:</p>

<pre>&lt;?xml version="1.0" encoding='UTF-8'?></pre></li>
<li><p>A <tt>faces-config</tt> tag enclosing all the other declarations:</p>

<pre>&lt;faces-config version="2.0" xmlns="http://java.sun.com/xml/ns/javaee" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
   http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd"> 
   ...
&lt;/faces-config></pre></li></ul>
<p>You can have more than one application configuration resource file for an application.
The JavaServer Faces implementation finds the configuration file or files by looking for
the following:</p>


<ul><li><p>A resource named <tt>/META-INF/faces-config.xml</tt> in any of the JAR files in the web application&rsquo;s <tt>/WEB-INF/lib/</tt> directory and in parent class loaders. If a resource with this name exists, it is loaded as a configuration resource. This method is practical for a packaged library containing some components and renderers. In addition, any file with a name that ends in <tt>faces-config.xml</tt> is also considered a configuration resource and is loaded as such.</p>

</li>
<li><p><a name="indexterm-770"></a>A context initialization parameter, <tt>javax.faces.application.CONFIG_FILES</tt>, in your web deployment descriptor file that specifies one or more (comma-delimited) paths to multiple configuration files for your web application. This method is most often used for enterprise-scale applications that delegate to separate groups the responsibility for maintaining the file for each portion of a big application.</p>

</li>
<li><p>A resource named <tt>faces-config.xml</tt> in the <tt>/WEB-INF/</tt> directory of your application. Simple web applications make their configuration files available in this way.</p>

</li></ul>
<p><a name="indexterm-771"></a>To access the resources registered with the application, you can use an instance of
the <tt>Application</tt> class, which is automatically created for each application. The <tt>Application</tt> instance
acts as a centralized factory for resources that are defined in the XML
file.</p>

<p>When an application starts up, the JavaServer Faces implementation creates a single instance
of the <tt>Application</tt> class and configures it with the information that you provided
in the application configuration resource file.</p>



<a name="giqck"></a><h3>Ordering of Application Configuration Resource Files</h3>
<p>Because JavaServer Faces technology allows the use of multiple application configuration resource files
stored in different locations, the order in which they are loaded by the
implementation becomes important in certain situations (for example, when using application level objects).
This order can be defined through an <tt>ordering</tt> element and its sub-elements in
the application configuration resource file itself. The ordering of application configuration resource files can
be absolute or relative.</p>

<p>Absolute ordering is defined by an <tt>absolute-ordering</tt> element in the file. With absolute
ordering, the user specifies the order in which application configuration resource files will
be loaded. The following example shows an entry for absolute ordering:</p>

<p>File <tt>my-faces-config.xml</tt>:</p>

<pre>&lt;faces-config>
    &lt;name>myJSF&lt;/name>
    &lt;absolute-ordering>
        &lt;name>A&lt;/name>
        &lt;name>B&lt;/name>
        &lt;name>C&lt;/name>
    &lt;/absolute-ordering>
&lt;/faces-config></pre><p>In this example, A, B, and C are different application configuration resource files
and are to be loaded in the listed order.</p>

<p>If there is an <tt>absolute-ordering</tt> element in the file, only the files listed
by the sub-element <tt>name</tt> are processed. To process any other application configuration resource
files, an <tt>others</tt> sub-element is required. In the absence of the <tt>others</tt>
sub-element, all other unlisted files will be ignored at load time.</p>

<p>Relative ordering is defined by an <tt>ordering</tt> element and its sub-elements <tt>before</tt> and
<tt>after</tt>. With relative ordering, the order in which application configuration resource files will be
loaded is calculated by considering ordering entries from the different files. The following
example shows some of these considerations. In the following example, <tt>config-A</tt>, <tt>config-B</tt>, and <tt>config-C</tt>
are different application configuration resource files.</p>

<p>File <tt>config-A</tt> contains the following elements:</p>

<pre>&lt;faces-config>
    &lt;name>config-A&lt;/name>
    &lt;ordering>
        &lt;before>
            &lt;name>config-B&lt;/name>
        &lt;/before>
    &lt;/ordering>
&lt;/faces-config></pre><p>File <tt>config-B</tt> (not shown here) does not contain any <tt>ordering</tt> elements.</p>

<p>File <tt>config-C</tt> contains the following elements:</p>

<pre>&lt;faces-config>
    &lt;name>config-C&lt;/name>
    &lt;ordering>
        &lt;after>
            &lt;name>config-B&lt;/name>
        &lt;/after>
    &lt;/ordering>
&lt;/faces-config></pre><p>Based on the <tt>before</tt> sub-element entry, file <tt>config-A</tt> will be loaded before
the <tt>config-B</tt> file. Based on the <tt>after</tt>  sub-element entry, file <tt>config-C</tt> will
be loaded after the <tt>config-B</tt> file.</p>

<p>In addition, a sub-element <tt>others</tt> can also be nested within the <tt>before</tt> and
<tt>after</tt> sub-elements. If the <tt>others</tt> element is present, the file may receive highest or
lowest preference among both listed and unlisted configuration files.</p>

<p>If an <tt>ordering</tt> element is not present in an application configuration file, then
that file will receive the lowest order when being loaded, compared to the
files that contain an <tt>ordering</tt> element.</p>


         </div>
         <div class="navigation">
             <a href="girch.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="bnawq.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

